home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / javax / accessibility / AccessibleContext.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  19.1 KB  |  512 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)AccessibleContext.java    1.23 98/08/26
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package javax.accessibility;
  16.  
  17. import java.util.Locale;
  18. import java.beans.PropertyChangeListener;
  19. import java.beans.PropertyChangeSupport;
  20. import java.awt.IllegalComponentStateException;
  21.  
  22. /**
  23.  * AccessibleContext represents the minimum information all accessible objects
  24.  * return.  This information includes the accessible name, description, role,
  25.  * and state of the object, as well as information about the parent and 
  26.  * children of the object.  AccessibleContext also contains methods for
  27.  * obtaining more specific accessibility information about a component.
  28.  * If the component supports it, these methods will return an object that
  29.  * implements one or more of the following interfaces:
  30.  * <P><ul>
  31.  * <li>{@link AccessibleAction} - the object can perform one or more actions.  
  32.  * This interface provides the standard mechanism for an assistive
  33.  * technology to determine what those actions are and tell the object
  34.  * to perform those actions.  Any object that can be manipulated should
  35.  * support this interface.
  36.  * <li>{@link AccessibleComponent} - the object has a graphical representation.
  37.  * This interface provides the standard mechanism for an assistive 
  38.  * technology to determine and set the graphical representation of the 
  39.  * object.  Any object that is rendered on the screen should support
  40.  * this interface.
  41.  * <li>{@link  AccessibleSelection} - the object allows its children to be 
  42.  * selected.  This interface provides the standard mechanism for an
  43.  * assistive technology to determine the currently selected children
  44.  * as well as modify the selection set.  Any object that has children
  45.  * that can be selected should support this interface.
  46.  * <li>{@link AccessibleText} - the object presents editable textual information
  47.  * on the display.  This interface provides the standard mechanism for
  48.  * an assistive technology to access that text via its content, attributes,
  49.  * and spatial location.  Any object that contains editable text should
  50.  * support this interface.
  51.  * <li>{@link AccessibleValue} - the object supports a numerical value.  This
  52.  * interface provides the standard mechanism for an assistive technology
  53.  * to determine and set the current value of the object, as well as the
  54.  * minimum and maximum values.  Any object that supports a numerical value
  55.  * should support this interface.</ul>
  56.  * <P>In the future, additional interfaces (e.g., AccessibleTable) may be 
  57.  * added, and the abstract class AccessibleContext will be updated
  58.  * accordingly.
  59.  *
  60.  * @version     1.17 02/04/98 11:50:50
  61.  * @author    Peter Korn
  62.  * @author      Hans Muller
  63.  * @author      Willie Walker
  64.  */
  65. public abstract class AccessibleContext {
  66.  
  67.    /**
  68.     * Constant used to determine when the accessibleName property has
  69.     * changed.  The old value in the PropertyChangeEvent will be the old 
  70.     * accessibleName and the new value will be the new accessibleName.
  71.     *
  72.     * @see #getAccessibleName
  73.     * @see #addPropertyChangeListener
  74.     */
  75.    public static final String ACCESSIBLE_NAME_PROPERTY = "AccessibleName";
  76.  
  77.    /**
  78.     * Constant used to determine when the accessibleDescription property has
  79.     * changed.  The old value in the PropertyChangeEvent will be the
  80.     * old accessibleDescription and the new value will be the new
  81.     * accessibleDescription.
  82.     *
  83.     * @see #getAccessibleDescription
  84.     * @see #addPropertyChangeListener
  85.     */
  86.    public static final String ACCESSIBLE_DESCRIPTION_PROPERTY = "AccessibleDescription";
  87.  
  88.    /**
  89.     * Constant used to determine when the accessibleStateSet property has 
  90.     * changed.  The old value will be the old AccessibleState and the new
  91.     * value will be the new AccessibleState in the accessibleStateSet.  
  92.     * For example, if a component that supports the vertical and horizontal
  93.     * states changes its orientation from vertical to horizontal, the old
  94.     * value will be AccessibleState.VERTICAL and the new value will be
  95.     * AccessibleState.HORIZONTAL.  Please note that either value can also 
  96.     * be null.  For example, when a component changes from being enabled 
  97.     * to disabled, the old value will be AccessibleState.ENABLED
  98.     * and the new value will null.
  99.     *
  100.     * @see #getAccessibleStateSet
  101.     * @see AccessibleState
  102.     * @see AccessibleStateSet
  103.     * @see #addPropertyChangeListener
  104.     */
  105.    public static final String ACCESSIBLE_STATE_PROPERTY = "AccessibleState";
  106.  
  107.    /**
  108.     * Constant used to determine when the accessibleValue property has
  109.     * changed.  The old value in the PropertyChangeEvent will be a Number 
  110.     * representing the old value and the new value will be a Number 
  111.     * representing the new value.
  112.     *
  113.     * @see #getAccessibleValue
  114.     * @see #addPropertyChangeListener
  115.     */
  116.    public static final String ACCESSIBLE_VALUE_PROPERTY = "AccessibleValue";
  117.  
  118.    /**
  119.     * Constant used to determine when the accessibleSelection has changed.
  120.     * The old and new values in the PropertyChangeEvent are currently 
  121.     * reserved for future use.
  122.     *
  123.     * @see #getAccessibleSelection
  124.     * @see #addPropertyChangeListener
  125.     */
  126.    public static final String ACCESSIBLE_SELECTION_PROPERTY = "AccessibleSelection";
  127.  
  128.    /**
  129.     * Constant used to determine when the accessibleText has changed.
  130.     * The old and new values in the PropertyChangeEvent are currently 
  131.     * reserved for future use.
  132.     *
  133.     * @see #getAccessibleText
  134.     * @see #addPropertyChangeListener
  135.     */
  136.    public static final String ACCESSIBLE_TEXT_PROPERTY = "AccessibleText";
  137.  
  138.    /**
  139.     * Constant used to determine when the accessibleText caret has changed.
  140.     * has changed.  The old value in the PropertyChangeEvent will be an
  141.     * integer representing the old caret position, and the new value will 
  142.     * be an integer representing the new/current caret position.
  143.     *
  144.     * @see #addPropertyChangeListener
  145.     */
  146.    public static final String ACCESSIBLE_CARET_PROPERTY = "AccessibleCaret";
  147.  
  148.    /**
  149.     * Constant used to determine when the visual appearance of the object
  150.     * has changed.  The old and new values in the PropertyChangeEvent are 
  151.     * currently reserved for future use.
  152.     *
  153.     * @see #addPropertyChangeListener
  154.     */
  155.    public static final String ACCESSIBLE_VISIBLE_DATA_PROPERTY = "AccessibleVisibleData";
  156.  
  157.    /**
  158.     * Constant used to determine when Accessible children are added/removed
  159.     * from the object.  If an Accessible child is being added, the old
  160.     * value will be null and the new value the Accessible child.  If an
  161.     * Accessible child is being removed, the old value will be the Accessible
  162.     * child, and the new value will be null.
  163.     *
  164.     * @see #addPropertyChangeListener
  165.     */
  166.    public static final String ACCESSIBLE_CHILD_PROPERTY = "AccessibleChild";
  167.  
  168.    /**
  169.     * Constant used to determine when the active descendant of a component
  170.     * has changed.  The active descendant is used for objects such as 
  171.     * list, tree, and table, which may have transient children.  When the
  172.     * active descendant has changed, the old value of the property change
  173.     * event will be the Accessible representing the previous active child, and 
  174.     * the new value will be the Accessible representing the current active
  175.     * child.
  176.     *
  177.     * @see #addPropertyChangeListener
  178.     */
  179.    public static final String ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY = "AccessibleActiveDescendant";
  180.  
  181.     /** 
  182.      * The accessible parent of this object.
  183.      *
  184.      * @see #getAccessibleParent
  185.      * @see #setAccessibleParent
  186.      */
  187.     protected Accessible accessibleParent = null;
  188.  
  189.     /**
  190.      * A localized String containing the name of the object.
  191.      *
  192.      * @see #getAccessibleName
  193.      * @see #setAccessibleName 
  194.      */
  195.     protected String accessibleName = null;
  196.  
  197.     /**
  198.      * A localized String containing the description of the object.
  199.      *
  200.      * @see #getAccessibleDescription
  201.      * @see #setAccessibleDescription 
  202.      */
  203.     protected String accessibleDescription = null;
  204.  
  205.     /**
  206.      * Used to handle the listener list for property change events.
  207.      *
  208.      * @see #addPropertyChangeListener
  209.      * @see #removePropertyChangeListener
  210.      * @see #firePropertyChangeListener
  211.      */
  212.     private PropertyChangeSupport accessibleChangeSupport = null;
  213.  
  214.     /**
  215.      * Get the accessibleName property of this object.  The accessibleName
  216.      * property of an object is a localized String that designates the purpose
  217.      * of the object.  For example, the accessibleName property of a label
  218.      * or button might be the text of the label or button itself.  In the
  219.      * case of an object that doesn't display its name, the accessibleName
  220.      * should still be set.  For example, in the case of a text field used
  221.      * to enter the name of a city, the accessibleName for the en_US locale
  222.      * could be 'city.'
  223.      *
  224.      * @return the localized name of the object; null if this 
  225.      * object does not have a name
  226.      *
  227.      * @see #setAccessibleName
  228.      */
  229.     public String getAccessibleName() {
  230.     return accessibleName;
  231.     }
  232.     
  233.     /**
  234.      * Set the localized accessible name of this object.  Changing the
  235.      * name will cause a PropertyChangeEvent to be fired for the
  236.      * ACCESSIBLE_NAME_PROPERTY property.
  237.      *
  238.      * @param s the new localized name of the object.
  239.      *
  240.      * @see #getAccessibleName
  241.      * @see #addPropertyChangeListener
  242.      */
  243.     public void setAccessibleName(String s) {
  244.     String oldName = accessibleName;
  245.     accessibleName = s;
  246.     firePropertyChange(ACCESSIBLE_NAME_PROPERTY,oldName,accessibleName);
  247.     }
  248.  
  249.     /**
  250.      * Get the accessibleDescription property of this object.  The
  251.      * accessibleDescription property of this object is a short localized
  252.      * phrase describing the purpose of the object.  For example, in the 
  253.      * case of a 'Cancel' button, the accessibleDescription could be
  254.      * 'Ignore changes and close dialog box.'
  255.      *
  256.      * @return the localized description of the object; null if 
  257.      * this object does not have a description
  258.      *
  259.      * @see #setAccessibleDescription
  260.      */
  261.     public String getAccessibleDescription() {
  262.     return accessibleDescription;
  263.     }
  264.  
  265.     /**
  266.      * Set the accessible description of this object.  Changing the
  267.      * name will cause a PropertyChangeEvent to be fired for the
  268.      * ACCESSIBLE_DESCRIPTION_PROPERTY property.
  269.      *
  270.      * @param s the new localized description of the object
  271.      *
  272.      * @see #setAccessibleName
  273.      * @see #addPropertyChangeListener
  274.      */
  275.     public void setAccessibleDescription(String s) {
  276.     String oldDescription = accessibleDescription;
  277.     accessibleDescription = s;
  278.     firePropertyChange(ACCESSIBLE_DESCRIPTION_PROPERTY,
  279.                oldDescription,accessibleDescription);
  280.     }
  281.  
  282.     /**
  283.      * Get the role of this object.  The role of the object is the generic
  284.      * purpose or use of the class of this object.  For example, the role
  285.      * of a push button is AccessibleRole.PUSH_BUTTON.  The roles in 
  286.      * AccessibleRole are provided so component developers can pick from
  287.      * a set of predefined roles.  This enables assistive technologies to
  288.      * provide a consistent interface to various tweaked subclasses of 
  289.      * components (e.g., use AccessibleRole.PUSH_BUTTON for all components
  290.      * that act like a push button) as well as distinguish between sublasses
  291.      * that behave differently (e.g., AccessibleRole.CHECK_BOX for check boxes
  292.      * and AccessibleRole.RADIO_BUTTON for radio buttons).
  293.      * <p>Note that the AccessibleRole class is also extensible, so 
  294.      * custom component developers can define their own AccessibleRole's
  295.      * if the set of predefined roles is inadequate.
  296.      *
  297.      * @return an instance of AccessibleRole describing the role of the object
  298.      * @see AccessibleRole
  299.      */
  300.     public abstract AccessibleRole getAccessibleRole();
  301.     
  302.     /**
  303.      * Get the state set of this object.  The AccessibleStateSet of an object
  304.      * is composed of a set of unique AccessibleState's.  A change in the 
  305.      * AccessibleStateSet of an object will cause a PropertyChangeEvent to 
  306.      * be fired for the ACCESSIBLE_STATE_PROPERTY property.
  307.      *
  308.      * @return an instance of AccessibleStateSet containing the 
  309.      * current state set of the object
  310.      * @see AccessibleStateSet
  311.      * @see AccessibleState
  312.      * @see #addPropertyChangeListener
  313.      */
  314.     public abstract AccessibleStateSet getAccessibleStateSet();
  315.  
  316.     /**
  317.      * Get the Accessible parent of this object.
  318.      *
  319.      * @return the Accessible parent of this object; null if this
  320.      * object does not have an Accessible parent
  321.      */
  322.     public Accessible getAccessibleParent() {
  323.     return accessibleParent;
  324.     }
  325.  
  326.     /**
  327.      * Set the Accessible parent of this object.  This is meant to be used
  328.      * only in the situations where the actual component's parent should 
  329.      * not be treated as the component's accessible parent and is a method 
  330.      * that should only be called by the parent of the accessible child. 
  331.      *
  332.      * @param a - Accessible to be set as the parent    
  333.      */
  334.     public void setAccessibleParent(Accessible a) {
  335.         accessibleParent = a;
  336.     }
  337.  
  338.     /**
  339.      * Get the 0-based index of this object in its accessible parent.
  340.      *
  341.      * @return the 0-based index of this object in its parent; -1 if this 
  342.      * object does not have an accessible parent.
  343.      *
  344.      * @see #getAccessibleParent 
  345.      * @see #getAccessibleChildrenCount
  346.      * @see #getAccessibleChild
  347.      */
  348.     public abstract int getAccessibleIndexInParent();
  349.  
  350.     /**
  351.      * Returns the number of accessible children of the object.
  352.      *
  353.      * @return the number of accessible children of the object.
  354.      */
  355.     public abstract int getAccessibleChildrenCount();
  356.  
  357.     /**
  358.      * Return the specified Accessible child of the object.  The Accessible
  359.      * children of an Accessible object are zero-based, so the first child 
  360.      * of an Accessible child is at index 0, the second child is at index 1,
  361.      * and so on.
  362.      *
  363.      * @param i zero-based index of child
  364.      * @return the Accessible child of the object
  365.      * @see #getAccessibleChildrenCount
  366.      */
  367.     public abstract Accessible getAccessibleChild(int i);
  368.  
  369.     /** 
  370.      * Gets the locale of the component. If the component does not have a 
  371.      * locale, then the locale of its parent is returned.  
  372.      *
  373.      * @return This component's locale.  If this component does not have 
  374.      * a locale, the locale of its parent is returned.
  375.      *
  376.      * @exception IllegalComponentStateException 
  377.      * If the Component does not have its own locale and has not yet been 
  378.      * added to a containment hierarchy such that the locale can be
  379.      * determined from the containing parent. 
  380.      */
  381.     public abstract Locale getLocale() throws IllegalComponentStateException;
  382.  
  383.     /**
  384.      * Add a PropertyChangeListener to the listener list.
  385.      * The listener is registered for all Accessible properties and will
  386.      * be called when those properties change.
  387.      *
  388.      * @see #ACCESSIBLE_NAME_PROPERTY
  389.      * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
  390.      * @see #ACCESSIBLE_STATE_PROPERTY
  391.      * @see #ACCESSIBLE_VALUE_PROPERTY
  392.      * @see #ACCESSIBLE_SELECTION_PROPERTY
  393.      * @see #ACCESSIBLE_TEXT_PROPERTY
  394.      * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
  395.      *
  396.      * @param listener  The PropertyChangeListener to be added
  397.      */
  398.     public void addPropertyChangeListener(PropertyChangeListener listener) {
  399.         if (accessibleChangeSupport == null) {
  400.             accessibleChangeSupport = new PropertyChangeSupport(this);
  401.         }
  402.         accessibleChangeSupport.addPropertyChangeListener(listener);
  403.     }
  404.  
  405.     /**
  406.      * Remove a PropertyChangeListener from the listener list.
  407.      * This removes a PropertyChangeListener that was registered
  408.      * for all properties.
  409.      *
  410.      * @param listener  The PropertyChangeListener to be removed
  411.      */
  412.     public void removePropertyChangeListener(PropertyChangeListener listener) {
  413.         if (accessibleChangeSupport != null) {
  414.             accessibleChangeSupport.removePropertyChangeListener(listener);
  415.         }
  416.     }
  417.  
  418.     /**
  419.      * Get the AccessibleAction associated with this object that supports
  420.      * one or more actions. 
  421.      *
  422.      * @return AccessibleAction if supported by object; else return null
  423.      * @see AccessibleAction
  424.      */
  425.     public AccessibleAction getAccessibleAction() {
  426.     return null;
  427.     }
  428.  
  429.     /**
  430.      * Get the AccessibleComponent associated with this object that has a 
  431.      * graphical representation.
  432.      *
  433.      * @return AccessibleComponent if supported by object; else return null
  434.      * @see AccessibleComponent
  435.      */
  436.     public AccessibleComponent getAccessibleComponent() {
  437.     return null;
  438.     }
  439.  
  440.     /**
  441.      * Get the AccessibleSelection associated with this object which allows its
  442.      * Accessible children to be selected.  
  443.      * 
  444.      * @return AccessibleSelection if supported by object; else return null
  445.      * @see AccessibleSelection
  446.      */
  447.     public AccessibleSelection getAccessibleSelection() {
  448.     return null;
  449.     }
  450.  
  451. //    /**
  452. //     * Get the AccessibleTable associated with this object if one
  453. //     * exists.  Otherwise return null.
  454. //     */
  455. //    public AccessibleTable getAccessibleTable() {
  456. //        return null;
  457. //    }
  458.  
  459.     /**
  460.      * Get the AccessibleText associated with this object presently editable
  461.      * text on the display.
  462.      *
  463.      * @return AccessibleText if supported by object; else return null
  464.      * @see AccessibleText
  465.      */
  466.     public AccessibleText getAccessibleText() {
  467.     return null;
  468.     }
  469.  
  470.     /**
  471.      * Get the AccessibleValue associated with this object that supports a 
  472.      * Numerical value. 
  473.      * 
  474.      * @return AccessibleValue if supported by object; else return null 
  475.      * @see AccessibleValue
  476.      */
  477.     public AccessibleValue getAccessibleValue() {
  478.     return null;
  479.     }
  480.  
  481.     /**
  482.      * Support for reporting bound property changes.  If oldValue and 
  483.      * newValue are not equal and the PropertyChangeEvent listener list 
  484.      * is not empty, then fire a PropertyChange event to each listener.
  485.      * In general, this is for use by the Accessible objects themselves
  486.      * and should not be called by an application program.
  487.      * @param propertyName  The programmatic name of the property that
  488.      * was changed.
  489.      * @param oldValue  The old value of the property.
  490.      * @param newValue  The new value of the property.
  491.      * @see java.beans.PropertyChangeSupport
  492.      * @see #addPropertyChangeListener
  493.      * @see #removePropertyChangeListener
  494.      * @see #ACCESSIBLE_NAME_PROPERTY
  495.      * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
  496.      * @see #ACCESSIBLE_STATE_PROPERTY
  497.      * @see #ACCESSIBLE_VALUE_PROPERTY
  498.      * @see #ACCESSIBLE_SELECTION_PROPERTY
  499.      * @see #ACCESSIBLE_TEXT_PROPERTY
  500.      * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
  501.      */
  502.     public void firePropertyChange(String propertyName, 
  503.                    Object oldValue, 
  504.                    Object newValue) {
  505.         if (accessibleChangeSupport != null) {
  506.         accessibleChangeSupport.firePropertyChange(propertyName, 
  507.                                oldValue, 
  508.                                newValue);
  509.     }
  510.     }
  511. }
  512.